jPSXdec 0.93.1 (alpha) Manual

Michael Sabin

jpsxdec@gmail.com

Table of Contents

1 About
1.1 Java frameworks
2 Command-line
2.1 Quick start
2.2 Main command-line options
2.3 Options for disc item types
3 File formats recognized by jPSXdec
4 Index files
5 Building from source
6 License



1 About

jPSXdec is a PlayStation 1 media reader, decoder, and converter written using the Java framework.

Because jPSXdec uses the Java framework, it makes it almost universally cross-platform, but does require Java to be installed to work.

jPSXdec can read from any file or image that comes from PlayStation discs. It is recommended that the entire disc be ripped as a BIN/CUE file, but you may have some success from ripping or copying individual files off the disc.

1.1 Java frameworks

There are several Java Virtual Machines and frameworks available. jPSXdec has only been tested on Oracle's Java.

2 Command-line

2.1 Quick start

First the source file (whether it be a disc image or a single media file) needs to be analyzed and an index generated.

Example to generate an index:

java -jar jpsxdec.jar MyGameImage.bin -index MyGameImage.idx



Once the index is created, open it to review what was found in the source file.

Identify the number of an item you are interested in, and run the command to extract/decode it.

Example to decode the first (0th) item:

java -jar jpsxdec.jar MyGameImage.bin -index MyGameImage.idx -d 0

2.2 Main command-line options

java -jar jpsxdec.jar -?/-h/-help

Displays main help.

java -jar jpsxdec.jar <in_file> <main_command_and_options>

Do something with <in_file> using one of the following <main_command_and_options>:

-index/-idx/-i <index_file>

Create an index for in_file

[-index/-idx/-i <index_file>] -?/-h/-help #

Display help about the disc item #

[-index/-idx/-i <index_file>] -decode/-d # [processing_options]

Decode disc item #, using optional <index_file> and optional [processing_options] (see item's help for options)

[-index/-idx/-i <index_file>] -a <media_type> [processing_options]

Decode all disc items of type <media_type>, using optional <index_file> and optional [processing_options] (see item type's help for options)

[-index/-idx/-i <index_file>] -play #

Opens a very simple player to play movies and audio

-copysect { # | #-# } <out_file>

Copy sectors to <out_file>

-sectordump <out_file>

Write list of sector types to <out_file> (for debugging)

[-index/-idx/-i <index_file>] -strreplace # <str_replace_xml>

Replaces frames of a video item according to the options in the xml file

Additional option (optional):

-v/-verbose #

How much info to print: 0 for none, 1 for only errors, 2 for errors & warnings, 3 for normal, 4 for extra

2.3 Options for disc item types

jPSXdec can detect the following data on PlayStation discs.

STR Video

All types of PlayStation videos.

For the highest quality output, use these flags:

-quality high+ -vf avi:rgb

The PlayStation doesn't require videos to have a consistent frame rate. As such, some games have movies with variable frame rates, and most games have movies where the frame rate isn't precisely as detected by jPSXdec (but the variance isn't perceivable). When saving videos as an image sequence, rate variations are ignored. When saving as AVI, jPSXdec tries to place the frames in the AVI time-line as close to where they belong. This may mean that duplicate frames are inserted into the movie (but AVI files have a convenient feature so duplication adds almost no extra size to files). Silent audio may also be inserted as needed in rare cases to keep the audio in sync. For more precise output, the -preceiseav and -precisefps options are available.

Command-line options
-quality <low, high, high+, psx>

Selects the decoding quality. Default is low. Option ignored if saving as demux or mdec format.

low quality is very fast, and uses integer based arithmetic.

high is much slower, but should create better output because it uses floating point arithmetic (although it may not be noticeable without close inspection). It uses nearest-neighbor interpolation for chroma upsampling.

high+ is like high, but uses bilinear interpolation for chroma upsampling for a very noticeable quality improvement.

psx quality tries to duplicate what the PlayStation would generate. It's not perfect, but is currently better than any other decoder ever written.

-vidfmt/-vf <format>

Selects the output format (default is avi:mjpg):

avi:mjpg – Smallest output, but it is a lossy format so quality may be degraded. Use the -jpg option to set compression/quality level.

avi:rgb – Completely uncompressed, RGB (device independent bitmap, i.e. DIB) AVI. Very large, but lossless.

avi:yuv – Highest quality output, and smaller even than avi:rgb. Uses the fourcc YV12 codec.

png, jpg, bmp – Saves a series of images.

demux – Raw, compressed bitstream frame data found in separate sectors on the disc. 'Demuxing' is the first step in the decoding process, which simply combines the separate frame chunks into a contiguous block.

mdec – Generated from the demux data. This data would then be fed into the PlayStation MDEC chip, which would produce viewable images.

-jpg <#>

Selects the quality between 0 and 100 when saving a sequence of jpeg images, or as AVI with MJPG codec. Default is 75.

-frame <#> / -frames <#-#>

Lets you specify that only 1 frame, or a range of frames should be decoded. Audio is ignored when using this option because accurate audio decoded must begin from the start of the audio stream (you can't start in the middle).

-noaud

Don't decode audio with the video (ignored when video does not have audio, or when not saving as AVI).

-preciseav

By default, when saving the audio and video as an AVI, they are set to start playing at precisely the same time. While that is probably how the video was intended to be seen, that is not exactly how it is played back on the PlayStation. The audio most likely starts where it first appears on the disc, which could be up to 0.15 seconds after the video starts. This option saves the audio and video to begin exactly when they appear on the disc (option ignored if not saving AVI with audio).

-nocrop

PlayStation 1 movies technically must have dimensions that are multiples of 16. In cases where games need movies that do not have such dimensions, the extra space is filled with garbage and is cropped off before being drawn on screen. When this option is used, that extra data is not cropped. Option ignored if saving as demux or mdec format.

-x <1 or 2>

Movie frame rates are entirely dependent on the speed the disc spins. PlayStation 1 can spin discs at 1x speed, or 2x speed. Nearly every game I've seen uses 2x speed for all their movies. jPSXdec can usually automatically detect the disc speed by analysis of parallel audio streams, but if the speed is unclear, it will assume 2x. In the rare case that is incorrect, this option lets you force using 1x disc speed instead (effectively halving the frame-rate). Option ignored if not saving as avi.

-precisefps

Like the option above, the frame rate for most videos isn't exactly how the video is actually played back on the PlayStation. This option will save the AVI with frames appearing exactly how they are arranged on the disc, which will give the video a 75 or 150 fps rate (option ignored if not saving AVI with audio).

XA Audio & Square Audio

Standard XA ADPCM audio used by Sony PlayStation 1 and Phillips CD-i, and audio from Square (now SquareEnix) games (e.g. Final Fantasy).

Command-line options
-vol <number between 0 and 100>

This does more than just adjust the volume, because it does the adjustment before clamping the waveform and rounding it to an integer volume. Therefore the output should be better quality when scaling the volume at this point, and can even help in cases where a game's audio has distortions due to the clamping. Default is 100.

-audfmt / -af <format>

Output audio format. Use the item's help to see what options are available. Default is .wav.

File (ISO9660)

Normal files on disc images are detected and can be extracted and saved. Note that jPSXdec ignores the file size and just saves the full sectors.

Command-line options
-iso

jPSXdec can detect 4 different styles of disc images (raw+subchannel 2448 bytes/sector, raw 2352 bytes/sector, special 2336 bytes/sector, and iso 2048 bytes/sector). By default, files from these disc images are copied out with the same style as the source disc image. With this -iso option, all raw sector headers are ignored and the file is saved as if it had been normally copied off a disc. Care must be taken that this option isn't used on files containing XA audio streams, as that raw header information is required for decoding them.

TIM image

Simple TIM images regularly used in PlayStation games.

Command-line options
-imgfmt / -if <image format>

Format to save the TIM image. Use item's help for available options. These options will be different depending on if the TIM image has a palette. Default is png.

-pal <palettes to save>

TIM images may come with one or more palettes. By default, all palettes are saved as a separate output files. This option lets you only select exactly which palettes to save using a comma delimited list, or hyphens (no spaces). For example, to save the first and third, fourth and firth palettes, you could use this:

-pal 1,3-5

3 File formats recognized by jPSXdec

jPSXdec can read and understand two main file formats: disc images in the form of ISO and BIN/CUE. Since it can read BIN/CUE disc images, it can also read .STR and .XA files because those files are simply extracted portions of BIN/CUE disc images.

4 Index files

Index files contain important information about the contents of a disc image or media file. jPSXdec needs the index before it can perform any operations on a source file.

Index files may be edited by hand. If there's something wrong, jPSXdec will let you know.

All audio and video streams are listed separately, even if they should probably be combined. Actions upon video streams will also consider any parallel audio streams.

5 Building from source

An Ant build script has been included. If Ant is installed and configured properly, simply running the ant command in the directory with build.xml will generate a directory containing the binary program and everything needed to distribute it.

6 License

jPSXdec is licensed under a non-commercial license. See LICENSE.txt for details. If you would like to use jPSXdec in a way that is incompatible with this license, let me know. I am quite willing to make exceptions on a case-by-case bases. If you think your request is reasonable, I probably will too.